home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 1999 March - Disc 1 / Macworld (1999-03) (Disk 1).dmg / Shareware World / Utilities / Text Processing / Alpha / Help / Error Help < prev    next >
Encoding:
Text File  |  1998-05-02  |  9.4 KB  |  305 lines  |  [TEXT/ALFA]
  1. ###################################################################
  2.  Alpha Error Handlers
  3.  
  4.                                    created: 4/9/98 {10:32:09 PM} 
  5.                                last update: 5/2/98 {5:30:31 PM} 
  6.  Author: Jonathan Guyer
  7.  E-mail: <jguyer@his.com>
  8.     www: <http://www.his.com/~jguyer/>
  9.  
  10.  Copyright (c) 1998  Jonathan Guyer
  11.  
  12. ###################################################################
  13.  
  14. This package is free software; you can redistribute it and/or modify
  15. it under the terms of the GNU General Public License.
  16.  
  17. ###################################################################
  18.  
  19. This package provides a uniform mechanism for catching, handling, 
  20. and displaying errors. The key to all this functionality is the
  21. try construct, similar to that available in C++ or AppleScript. The 
  22. default error handler will display any errors in accordance with 
  23. the current user preferences (Config->Global->Preferences->Errors).
  24.  
  25. Errors can be reported in one of four levels of detail:
  26.  
  27.     taciturn: display the error message in the message bar.
  28.     
  29.     terse: display the error message in a dialog.
  30.     
  31.     verbose: display the error message and the error code in
  32.         a dialog.
  33.     
  34.     pedantic: display the error message, the error code, and
  35.         whatever context is available through errorInfo in
  36.         a window.
  37.     
  38. A fifth option is available only through the -reporting parameter 
  39. to try, and is primarily for use by Alpha's startup code:
  40.  
  41.     log: display the error message, the error code, and
  42.         whatever context is available through errorInfo in
  43.         either the startup log or the in the Tcl shell, if
  44.         available, after alerting the user to the error.
  45.         
  46. Examples:
  47.  
  48.     The script
  49.  
  50.         try {
  51.             error "this is the error" "" "this is the code"
  52.         }
  53.     
  54.     will be reported as follows, depending on the value of 
  55.     errorReporting:
  56.     
  57.         taciturn: reports "this is the error" in the message bar.
  58.         
  59.         terse: reports "this is the error" in a dialog.
  60.         
  61.         verbose: reports
  62.         
  63.                 Message: "this is the error"
  64.                 Error Code: this is the code 
  65.                 
  66.             in a dialog.
  67.             
  68.         pedantic: reports
  69.         
  70.                 Message: "this is the error"
  71.                 Error Code: this is the code
  72.                     # while executing
  73.                 error "this is the error" "" "this is the code"
  74.                     # invoked from within
  75.                 try {error "this is the error" "" "this is the code"}
  76.                 
  77.             in a window (the window is displayed in Tcl mode for better 
  78.             readability). Pedantic reports can get, well, pedantic very 
  79.             quickly, but can be useful guides for debug tracing.
  80.             
  81.         log: reports
  82.         
  83.                 =======================
  84.                 try  error "this is the error" "" "this is the code" error
  85.                 this is the error
  86.                     invoked from within
  87.                 try {error "this is the error" "" "this is the code"}
  88.                 
  89.             in the Tcl shell (or in the startup log).
  90.             
  91.  
  92. In the event that there are errors that you don't wish to 
  93. display or which to handle in some special fashion, supply one or 
  94. more -onError scripts: 
  95.  
  96.     try {
  97.         eval $script
  98.     } -onError {
  99.         -34 {error::alertnote "Aughh!!! The disk is full!!!"}
  100.         12* {error::alertnote "VOODOO error: $errorMsg"}
  101.         default {}
  102.     }
  103.     
  104. will display a dialog reporting "Aughh!!! The disk is full!!!", if 
  105. you've executed
  106.  
  107.     set script {error "this is an error" "" "-34"}
  108.  
  109. a dialog reporting "VOODOO error: this is an error" if you've executed
  110.  
  111.     set script {error "this is an error" "" "12005"}
  112.     
  113. and does nothing at all for any other errors; in fact, 
  114.  
  115.     try {
  116.         eval $script
  117.     } -onError {
  118.         default {}
  119.     }
  120.     
  121. is identical to
  122.  
  123.     catch $script
  124.     
  125. (and is, hence, a pretty stupid use of try, since it's 
  126. noticeably slower). Another pointless use of try is
  127.  
  128.     try {
  129.         eval $script
  130.     } -onError {
  131.         default error::rethrow
  132.     }
  133.  
  134. which is identical to
  135.  
  136.     eval $script
  137.  
  138. (not to say that error::rethrow isn't handy, though).
  139.  
  140. Unless explicitly overridden, the default script will display all 
  141. errors not accounted for by other -onError scripts.  Always be sure to 
  142. put the default script last or none of the other onError scripts will 
  143. be executed.
  144.  
  145. The above case is OK, but rather than just catching 12000 series 
  146. VOODOO errors, it will also catch errorCodes of “123”, “12x”, 
  147. “12 buckle my shoe”, and so on. Better, in this instance, would be 
  148. to use the -regexp option
  149.  
  150.     try {
  151.         eval $script
  152.     } -onError {
  153.         -34 {error::alertnote "Aughh!!! The disk is full!!!"}
  154.         {12[0-9][0-9][0-9]} {error::alertnote "VOODOO error: $errorMsg"}
  155.         default {}
  156.     } -regexp
  157.     
  158. As usual, the default behavior is clearer; the -regexp behavior 
  159. is more powerful.
  160.  
  161.         
  162. A note about alertnotes: I have encountered an intermittent 
  163. crashing bug, which arises when an alertnote is displayed while 
  164. Alpha is in the background. As a result, an option is available, 
  165. both as a user preference and to individual try calls, to display 
  166. alertnote messages (terse and verbose reports) in a small window 
  167. instead. Display options are “alertnote always”, “alertnote 
  168. preferred”, and “window always”. Taciturn and pedantic reports 
  169. are unaffected by this setting.
  170.  
  171. _________________________________________________________________
  172.  
  173. NAME
  174.     try - Try to execute 'script'. 
  175. SYNOPSIS
  176.     try script ?options?
  177. _________________________________________________________________
  178.  
  179. DESCRIPTION
  180.     The try command executes its script argument in the stack frame that 
  181.     called it.  In the event of an error, try matches the global 
  182.     errorCode against each of any pattern arguments, specified by the 
  183.     -onError parameter, in order.  As soon as it finds a pattern that 
  184.     matches errorCode it evaluates the following body argument by 
  185.     passing it recursively to the Tcl interpreter and returns the 
  186.     result of that evaluation.  The last pattern argument is always a 
  187.     default to display the error (you may explicitly define a default 
  188.     argument if this behavior is not desired). Optionally, the errorMsg 
  189.     can be used for comparison, instead of errorCode.
  190.  
  191.     The syntax is largely that of switch, although the options follow 
  192.     script for both syntactic and performance reasons.  The default 
  193.     comparision mode for try is -glob, instead of -exact.  Unlike 
  194.     switch, try does not support separate pattern/command arguments; 
  195.     all must be provided as a list argument to the -onError optional 
  196.     parameter.  The following options are currently supported:
  197.     
  198.     -onError {pattern body ?pattern body ...?}: errorCode is compared to 
  199.         each pattern in order.  When a match is found, body is 
  200.         executed in the stack frame that called try.  If this option 
  201.         is missing, all errors will be displayed by the default 
  202.         routine.
  203.         
  204.     -exact: Use exact matching when comparing errorCode to a pattern.
  205.  
  206.     -glob: When matching errorCode to the patterns, use glob-style 
  207.         matching (i.e. the same as implemented by the string match 
  208.         command). This is the default.
  209.         
  210.     -regexp: When matching errorCode to the patterns, use regular
  211.         expression matching (i.e. the same as implemented by the regexp 
  212.         command).
  213.         
  214.     -display: Override the user's setting for errorDisplay.
  215.         Options are 'alertnote always', 'alertnote preferred', 
  216.         and 'window always'.
  217.     
  218.     -reporting: Override the user's setting for errorReporting.
  219.         Options are taciturn, terse, verbose, pedantic, and log.
  220.                 
  221.     -while: Short phrase to describe action taking place in event of an 
  222.         error.
  223.     
  224.     -code: Match errorCode against the -onError patterns. This is the 
  225.         default.
  226.         
  227.     -message: Match the errorMsg against the -onError patterns.
  228.  
  229.     The -onError scripts execute in the frame that calls try, so 
  230.     all variables local to that frame are available, as are the global 
  231.     variables errorCode, errorInfo, and errorMsg (without having 
  232.     to declare them global).
  233.     
  234.     If a body is specified as “-” it means that the  body  for
  235.     the  next  pattern  should also be used as the body for this
  236.     pattern (if the next pattern also has a body of  “-”  then
  237.     the body after that is used, and so on).  This feature makes
  238.     it possible to share a single body among several patterns.
  239.  
  240.     Below are some examples of try commands:
  241.  
  242.          try {
  243.              error "" "" aaab
  244.          } -onError {
  245.            ^a.*b$ -
  246.            b {format 1}
  247.            a* {format 2}
  248.            default {format 3}
  249.          } -regexp
  250.     will return 1, and
  251.  
  252.          try {
  253.              error "" "" xyz
  254.          } -onError {
  255.            a
  256.              -
  257.            b
  258.              {format 1}
  259.            a*
  260.              {format 2}
  261.            default
  262.              {format 3}
  263.          }
  264.     will return 3.
  265.     
  266.     NOTE: The old -depth option has been eliminated to allow delayed argument
  267.     processing, resulting in an 80% speed increase for error-free scripts. 
  268.     Instead of 
  269.  
  270.         try {script} -depth n
  271.  
  272.     now use
  273.  
  274.         try::level n {script}
  275.  
  276.     to achieve the same result.
  277.     
  278.     NOTE:
  279.     A 'try' block adds about 0.6 ticks to the execution of an error-free
  280.     script on my 7100/66 so, judiciously applied, there's not much of a penalty 
  281.     in using it. 
  282. _________________________________________________________________
  283.  
  284. NAME
  285.     try::level - Try to execute 'script' at specified 'level'.
  286. SYNOPSIS
  287.     try::level level args
  288. _________________________________________________________________
  289.  
  290. DESCRIPTION
  291.  
  292.     Try to execute a script at a specified level in the execution stack (see 
  293.     uplevel). The remaining arguments are those of try.
  294. _________________________________________________________________
  295.  
  296. NAME
  297.     error::rethrow - Rethrow a caught error
  298. SYNOPSIS
  299.     error::rethrow
  300. _________________________________________________________________
  301.  
  302. DESCRIPTION
  303.  
  304.     In the event that you catch an error you don't wish to handle, call 
  305.     this routine to send the error back to the caller.